HBuilderX 项目中集成 UnoCSS + 图标集
UnoCSS 是即时按需生成的原子化 CSS 引擎，相比 TailwindCSS 更加灵活、性能更好。本节讲解在 HBuilderX 初始化的 uni-app 项目中集成 UnoCSS 的完整流程，包括 CLI 模式配置、图标预设（preset-icons）集成、自动化脚本配置以及常见问题解决。
为什么选择 UnoCSS
| 对比项 | TailwindCSS | UnoCSS |
|---|---|---|
| 生成方式 | 扫描文件生成完整 CSS | 即时按需生成 |
| 性能 | 较慢（全量扫描） | 极快（即时编译） |
| 图标支持 | 需额外插件 | 内置 preset-icons |
| 自定义 | tailwind.config.js | unocss.config.ts（更灵活） |
| 小程序适配 | 需手动禁用多项 | 社区预设已处理 |
安装依赖
npm install -D unocss @unocss/cli unocss-preset-weapp @iconify/json
bash
| 依赖 | 说明 |
|---|---|
unocss | UnoCSS 核心 |
@unocss/cli | CLI 工具，用于非 Vite 项目 |
unocss-preset-weapp | 小程序预设，兼容 uni-app 写法 |
@iconify/json | 全部图标集（约 15 万个图标） |
如不需要全部图标，可以只安装特定图标集（如 @iconify-icons/mdi）。
配置 uno.config.ts
在项目根目录创建 uno.config.ts：
import { defineConfig, presetIcons, presetUno } from 'unocss'
import { transformerDirectives, transformerVariantGroup } from 'unocss'
export default defineConfig({
presets: [
presetUno(),
presetIcons({
scale: 1.2,
warn: true
})
],
transformers: [
transformerDirectives(),
transformerVariantGroup()
]
})
typescript
小程序预设（unocss-preset-weapp）的配置参考 uni-css-preset-weapp 开源项目，该预设兼容小程序中大部分 UnoCSS 写法。
CLI 命令配置
开发模式
npx unocss "pages/**/*.vue" "components/**/*.vue" "App.vue" -o ./static/uno.css --watch
bash
构建模式
npx unocss "pages/**/*.vue" "components/**/*.vue" "App.vue" -o ./static/uno.css --minify
bash
在 package.json 中添加脚本
{
"scripts": {
"unocss:dev": "unocss \"pages/**/*.vue\" \"components/**/*.vue\" \"App.vue\" -o ./static/uno.css --watch",
"unocss:build": "unocss \"pages/**/*.vue\" \"components/**/*.vue\" \"App.vue\" -o ./static/uno.css --minify"
}
}
json
在 main.js 中引入
import './static/uno.css'
javascript
图标预设使用
基本用法
安装 @iconify/json 后，可以直接在 class 中使用图标：
<template>
<!-- 格式：i-{集合名}-{图标名} -->
<view class="i-mdi-alarm" />
<view class="i-solar-play-bold" />
</template>
vue
图标名称查询
在 Icônes 网站上搜索图标，复制 class 名称。注意切换到正确的格式模式：
- 格式一：
i-solar-play-bold（UnoCSS 格式） - 格式二：
i-solar:play-bold（冒号分隔格式）
点击图标右侧的箭头可以切换格式。
验证集成
- 启动 UnoCSS 开发模式：
npm run unocss:dev - 在页面中添加测试 class：
<view class="text-2xl text-red-500 i-mdi-alarm">测试</view> - 检查
static/uno.css是否自动生成对应样式 - 在微信开发者工具中确认样式生效
自动化配置（vite.config.js）
为了在启动调试进程时自动运行 UnoCSS，可以配置 vite.config.js：
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { exec } from 'child_process'
export default defineConfig({
plugins: [uni()]
})
const mode = process.env.NODE_ENV
const cmd = mode === 'production'
? 'npm run unocss:build'
: 'npm run unocss:dev'
exec(cmd, { cwd: __dirname }, (error, stdout, stderr) => {
if (error) console.error('UnoCSS error:', error)
if (mode === 'production') console.log('UnoCSS 生产构建完成')
})
javascript
插件模式 vs CLI 模式
| 模式 | 说明 | 适用场景 |
|---|---|---|
| CLI 模式 | 通过命令行编译，输出到 static 目录 | HBuilderX 初始化的项目 |
| 插件模式 | 通过 Vite 插件集成，自动编译 | CLI 创建的项目（推荐） |
在 HBuilderX 项目中推荐 CLI 模式，因为 HBuilderX 的编译流程不完全支持 Vite 插件机制。
图标 CSS 生成的效果
当在页面中使用 i-mdi-alarm 时，UnoCSS 会自动生成：
.i-mdi-alarm {
/* 图标的 SVG 数据编码为 CSS background */
background: url("data:image/svg+xml,...") no-repeat;
background-size: 100% 100%;
display: inline-block;
width: 1em;
height: 1em;
}
css
图标以 CSS 背景的方式渲染，不需要额外的字体文件。
↑